MacFormat 1999 April/macformat-075.iso/Shareware Plus/Applications/Alpha/Help/Alpha Manual

Text File | 1998-12-19 | 84.0 KB | 1,997 lines | [TEXT/ALFA]

      Copyright © 1990-1998 Pete Keleher. All Rights Reserved

          (For more help, look under the system help menu!)

The Author(s) of this product are in no way liable for any direct or
indirect damage caused by the product.

You may freely copy and distribute Alpha, but please bear in mind that
Alpha is Shareware.  If you decide to keep it, please register your copy
by selecting 'Register' from the 'About…' dialog.

I am collecting user-written Tcl procs at Alpha's home site.  If you have
written anything that you think may be of general interest, please send it
to me and I will make it available.

Alpha contains source from many places, but in particular I'm grateful to
Ray Johnson and Tim Endres for their working on porting TCL to the mac, and
to Tom Scavo and Tom Pollard for their Tcl code contributions.  The
following people have also provided considerable code and/or help debugging
the one or two bugs Alpha has had: Masatsugu Nagata, Karl J. Smith, Eric
Sink, David C. Black, Richard T. Austin, Henry Spencer, Vince Darley,
Johan Linde, Tom Fetherston, Jon Guyer and Jerry Fowler.

What to do: USE THE MARKS MENU IN THIS FILE!.  This file contains "marks"
in a popup menu above the vertical scrollbar on the right, that let you
jump to different sections of this file.  Mouse-down on the M icon.

Also, Alpha supports a limited form of hypertext. Clicking on green
underlined text executes a command associated with the underlined text,
usually taking you to other documentation. Control-<period> will bring you
back.  For example, clicking here takes you to more documentation of the
hypertext capabilities.

Alpha's hypertext links can be used to perform arbitrary tasks, including
interaction with other applications.  Once you have Internet Config
installed, the following links will all be active:
    Alpha's home site:        click here (or here if no Internet Config)
    Mail to the author:        click here


Alpha is a very powerful, multi-purpose editor that allows any program-
or user-defined function to be bound to any keystroke, or placed into
user-defined menus. Every menu is defined in the macro language Tcl by
one of the startup files ("AlphaBits.tcl" or one of the files sourced
from inside it).

Alpha is multi-modal, which means it switches between different modes
depending on which type of document you are editing. Everybody who has used
Emacs knows about this concept. The idea with different modes is to change
Alpha's behavior depending on which kind of text you're editing. For
example if you're programming in C++ or editing a LaTeX document you of
course want different features.

Alpha uses Dr.  Ousterhout's Tool Command Language (Tcl) as an extension
language.  Click here for a more complete definition of the language.  Many
of the functions bound to keystrokes, as well as many of the functions in
the menus, are written in Tcl.

Of course, you don't have to learn Tcl to use Alpha. It is only needed if
you want to write your own extensions.

Callable functions in Alpha come in two different flavors.  First, there
are the basic Tcl commands, detailed here.  Second there are "Alpha commands",
commands that relate specifically to Alpha.

A good way to get to know the editor and the language is to try different
things out. Play around. Choose the menu item "Config:List All Bindings"
to get a listing of all the current keystroke bindings. Look in
"alphaMenus.tcl" for definitions of most of the menus. See the section on
"GUI Details" for more information about the various pieces of Alpha's
windows. And finally, please feel free to send suggestions/"feature"
reports/questions to me at <[e-mail]>. I am not able to answer US
postal mail, but if you send it to me I will at least read it. Have fun!



          GUI Details

Alpha's interface has several non-standard features. First, there is a
status window across the bottom of the primary window.

Second, the horizontal scrollbar can be turned on and off via the window
menu. The default for subsequent windows is controlled via the
global variable 'horScrollBar' (look under "Config:Global:Preferences:Window").

Third, above the vertical scrollbar on the right is an icon with curly braces
('{}'). This is the "Funcs" menu, which lists function definitions of the
the current window if the current mode is a programming language. By
default, the functions in this menu are sorted alphanumerically. This
feature can be turned off via the global flag 'sortFuncsMenu', making the
menu appear faster on slower machines.

Below the funcs menu is the "Marks" menu, which pops up over the icon with
the large 'M'. The "Marks" menu lists all marks for the current window,
and allows them to be cleared or automatically created (through the Tcl
proc 'markFile' that calls mode-specific routines). Above the "Funcs" menu,
a red disk icon appears if the window is currently dirty. Clicking on this
icon saves the file.

Directly above the vertical scrollbar is a black bar that can be used to
split any window into two independent panes showing the same buffer.
Windows are split by either dragging the black bar or using the
"Windows:Split Window" menu command. Windows are unsplit the same way.
Double-clicking on the bar can also be used to toggle whether the window
is split.

Clicking on the window name brings up a popup menu that shows the
complete pathname of the file.  Command-clicking anywhere else on the
titlebar brings up the mark menu. Option-clicking on the titlebar of a
window usually brings up a list of 'related' files.  What this means
depends upon the current mode. (Some modes don't use this features to list
files, but list something else instead.) For programming modes like C, C++,
Alpha asks your IDE: either the Symantec project manager or Metrowerks
CW IDE for a list of include files and shows them.  For TeX mode Alpha
lists all files which form part of the current document (if a
multi-part document).  A fallback is simply to list all files in the
current folder, if a mode doesn't supply its own implementation.

Option-clicking and dragging text enables rectangular editing.

Control-double-clicking on any type of paren or bracket hilites from the
paren or bracket to its mate.  Without the control key held down, only the
intervening text is selected.

Command-clicking on a selection passes it to the Internet Config app.
Command-clicking on a URL, selected or not, also passes it to Internet Config.

Cmd-double-clicking in *any* mode will attempt to open a URL in the
surrounding text and send it to your web browser. If this fails, Alpha then
tries a mode-specific procedure.

Command-double clicking on a word in a C file will try to find the
definition of the word. The first option is looking up the word in the
tag file. If the word is not a tag, or no tags have been specified, Alpha
attempts to lookup the word through the THINK Reference app. If you would like
Apple's Toolbox Assistant to be used instead, edit the proc
'C++::DblClick'. In Tcl mode, the verb is looked up in the Tcl folders,
then in ":Help:Alpha Commands", and then finally in ":Help:Tcl Commands".

Alpha also supports drag and drop editing.

The grow region in the lower right corner is replaced by a lock icon if the
file is read-only.  Read-only status can be changed by command-clicking in
this area.

See "Status Bar" for information describing the bar running across the
bottom of the screen.

Finally, Alpha provides many different ways to move windows around the
screen, most of which are accessible via the windows menu, i.e the menu
with the window icons. The first four items of the "Windows:Arrange" menu
move windows around a virtual box on the screen, defined by vars
'tileLeft', 'tileRight', 'tileWidth', and 'tileHeight'. The first two
affect 'numWinsToTile' windows, the others always affect two. The gap
between windows is controlled by 'tileMargin' (vertical) and 'horMargin'
(horizontal). These can be used to allow for different window types, such
as the one in system 8.0 and the one in earlier systems. The 'Unequal Vert' and
'Unequal Hor' items split the space between two windows, with the
proportion assigned to the first controlled by 'tileProportion'. All of
these variables can be changed via the "Config:Global:Preferences:Tiling"
dialog.



          Searches

Alpha has a full repertoire of searching commands.  The 'find' command
brings up a dialog allowing the search and replacement text to be
specified.  The dialog also allows 'Forward', 'Ignore Case', 'Reg Expr',
and 'Word Match' options to be set.  These options can be toggled via the
keyboard by clover-<first letter of option>.  For example, clover-w toggles
the 'Word Match' option.

The 'Mult Files' option tells Alpha to search through all files in a given
file set.  Filesets can be specified (see the section on
filesets) via the "New Fileset…" item of the "File
Sets:Utilities" sub-menu. Filesets can be chosen via the popup fileset menu.

In addition to the current filesets, the fileset menu has an entry called
"Directory Scan". Allows you to specify a folder that will be searched.
These folders are saved at the end of the menu for future searches.

Any search can also be a "Batch" search, a list of all matches in the
fileset or current window are displayed in a new window. A particular match
can be displayed by moving the cursor to a line in the file of matches and
selecting "Goto Match" from the Utils menu (also bound to "return").

And finally, Alpha allows a library of useful search and replace texts to
be defined as a tcl list of lists (each sublist containing a name, search
text, and replacement text). This list, the 'patternLibrary' variable
defined in 'search.tcl', is used to create a popup menu in the find dialog
allowing these patterns to be easily entered.

Once the text and options have been set, the 'Search' menu contains several
commands for repeated searching, replacing, etc.


          Regular Expressions

If the variable 'regExpr' is true, the search functions interpret the
search text as regular expressions, which have the following elements:

 c        literal char.
 ^        beginning of line.
 $        end of line.
 .        any character except carriage return.
 [...]    character class, can use ranges such as '0-9'.
          inside classes. Matches one character of the
          enclosed choices. Ex: '[ac0-2]' matches 'a',
          'c', '0', '1', or '2'.
 [^...]   negated character class, matches anything but
          the enclosed characters. ']' can be included
          by putting it immediately after the '^'.
 \t       tab.
 \r       carriage return or line break.
 *        zero or more occurrences of the previous
          pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
          'abbb' etc.
 +        one or more occurrences of the previous
          pattern.
 ?        zero or one occurrences of the previous
          pattern. Ex: 'ab?' matches 'a' or 'ab'.
 a|b      matches either a or b. If enclosed in
          parenthesis, the extent of the alternated
          expressions is limited. Ex: (pete|bob)
          matches either 'pete' or 'bob'.
 (...)    The interior elements are grouped together.

Regular expressions constructed from the above elements can be
concatenated to create larger expressions.

The parenthesis also define substrings of the total matched string that
can be used either later during substitution. The substring delimited by
the pair of parenthesis that includes the nth left paren is denoted \n,
where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.

EXAMPLE:
The following regular expression will match either 'aabox' or 'bbbox':

              (aa|bb)box

In addition, \w matches an alphanumeric character (including "_")
and \W a nonalphanumeric. Word boundaries may be matched by \b,
and non-boundaries by \B. A whitespace character is matched by
\s, non-whitespace by \S. A numeric character is matched by \d,
non-numeric by \D. You may use \w, \s and \d within character
classes.

The class of character recognized by \w (and hence not recognized
by \W), can be augmented via the 'addAlphaChars' command.

See here for more details.  Regular expressions can be very difficult to
master, but they the following section shows how useful they can be.



          Searches, Incremental

Emacs users will be happy that both forward and backward incremental
searches are implemented. Incremental searches bypass the normal search
dialog and search for the current text after each keystroke. The result is
often much faster and less intrusive. Executing either while an incremental
search is in progress causes the search to proceed to the next instance of
the current text. Incremental search mode is exited when any other command
(executed through the menus or through bindings that include at least one of
the control key and the option key) is executed, or when the escape or
delete key is used. Typing control-w while incremental search is active
causes all the characters to the end of the next word boundary to be
added to the search.


          Marks

Alpha allows the user to use "marks" to remember positions in files. Marks
"float". That is, if a mark is initially at position 312 and then five
characters are inserted at location 297, the mark's new value will be 317.
Alpha uses three different types of marks.

The first is generically referred to as "the mark". The mark is set to the
current insertion point by the command 'setMark' (control-space by
default). This requires that the Emacs feature is active. The position in
the file indicated by the blinking cursor is referred to as the current
insertion point. Many commands (such as "cut" and "copy") can operate
either on the currently selected (hilighted) text, or the text between the
current insertion point and "the mark". For example, if you move the cursor
to the beginning of the word "allybaba", hit control-space (the status bar
should say "Mark set"), move to the end of the word and hit option-w (the
status bar should say "Region copied"), the effect is the same as if you
had used the mouse to select the text and then selected the "Copy" command
from the "Edit" menu.

The second type of mark are the permanent marks. Permanent marks are set,
removed, and moved-to through the three corresponding menu items in the
"Search" menu. Permanent marks differ from the generic mark in that they
have names, there can be any number of them, and they are saved in the
resource fork if the file is subsequently saved.

Permanent marks can be accessed via the "Text:Named Marks" menu items, by
a popup menu called by mousing down on the M icon above a vertical
scrollbar, or by command-mousing on a window's titlebar.

The third type of mark is the temporary mark. Like permanent marks,
temporary marks can be named and there can be any number of them. Unlike
permanent marks, temporary marks do not "dirty" the file, and they aren't
saved. So far, temporary marks are used exclusively to implement higher
order functions in TCL procedures.

At the time a file is saved, the marks for that file are stored into the
file's resource fork.




          Colorizing

Alpha supports automatic "colorizing" of text. This is controlled by the
function 'regModeKeywords', which registers keywords to colorize in a
specific mode. Colorizing can be turned off via the 'coloring' flag.

You can add words to a given mode by opening a mode specific prefs file via
the "Config:Current Mode:Edit Prefs File" menu item, and using
regModeKeywords with the -a option.

Colors for keywords, strings, and comments (for applicable modes) can all
be changed via the "Config:Current Mode:Preferences" menu item.

C/C++ allows function calls to be colorized.  Alpha will colorize words
immediately before left parens, assuming that they are function calls.
Use "Config:Current Mode:Preferences" in C or C++ mode to turn this on.

Additionally, Alpha allows the text color and window background to be
changed. These are changed by redefining 'Foreground' and 'Background' in
the "Config:Redefine Colors" menu. The menu also allows all eight of the
primary colors to be redefined as well. For instance, you can redefine
'red', and any text that is currently red will then be the new color you
specify. Finally, there are eight other colors 'Color_9' through 'Color_15'
that can be used though regModeKeywords etc, and values for these can be
redefined as well.



          C/C++

"C" and "C++" modes are selected either automatically when the file is
opened, by suffix, or via the mode popup menu on the status bar.  The
suffixes mapped to any mode can be changed via "Config:Suffix Mappings…".
To set up '*.c' and '*.h' to map to C rather than C++, for instance, do the
following:
    1) open the suffixes dialog via "Config:Suffix Mappings…"
    2) remove *.c and *.h patterns from C++
    3) and add *.c and *.h to C.
That's it!

The rest of Alpha's support for C and C++ falls into four broad categories:
    • "electric" editing
    • colorizing
    • marking
    • interaction with CodeWarrior/Think

For electric editing, Alpha's default configuration is set up to perform
electric functions at left and right curly braces, semi-colons, and
carriage returns, all of which can be turned off via the
"Config:Current Mode:Menus And Features…" dialog.

Alpha's C and C++ modes can be configured with menus for
CodeWarrior, Symantec, Think Ref, and the Toolbox Assistant. You can prune
these to the two (or one) menu you want via the "Config:Current
Mode:Menus And Features…" menu item.

Alpha automatically colorizes key-words, #defines, comments, strings, and
function calls. All colors can be changed via "Config:Current
Mode:Preferences", or turned off entirely by selecting the "none" color option.
New key-words can be added by lines of the form:
    regModeKeywords -a -k blue C {newword1 newword2}
See the Colorizing section for more details.

The Mark menu, accessible from the the M icon above the vertical
scrollbar, allows C/C++ files to be automatically marked with a new mark
for each function in the file. You can jump to the resulting marks via the same
menu, command-clicking in the window's titlebar, or the "Text:Named
Marks:Goto" menu item. You can set up Alpha to automatically mark C/C++
files that don't have marks on opening by selecting 'autoMark' from the
"Config:Current Mode:Preferences" dialog.

Finally, Alpha is set up to closely cooperate with both Think and
Codewarrior. Follow the above links for more info.




          File Detritus

The primary method of either reading or storing files with Alpha, or any
other Mac editor, is through the GetFile and PutFile dialogs. However,
Alpha's dialogs are not exactly like those of other applications.

The GetFile dialog has two additional items: a "Read-only" checkbox and an
"All Files" checkbox.  The first allows you to open a file as read only.
Files in the read-only state can not be modified, only read.  A read-only
file is indicated by a lock icon replacing the grow zone icon.  Read-only
status can be toggled by command-clicking on the icon. The default action for
'space' and 'backspace' when a file is read-only is to page forward
(closing at the bottom of the file) or backward.

The second checkbox, "All Files", allows Alpha to open any file rather
than just those of type 'TEXT'. The type of a file can be determined by
using the 'll' alias in the Tcl shell.


The PutFile dialog is used to prompt the user for a new name under which to
save the contents of a window. This dialog has been enhanced by two popup
menus: "State" and "Format". "State" allows you to specify how much
information should be saved in the resource fork of files that you use. If
the state is set to "MPW", window position, current selection, tab sizes,
and font information are saved into the resource fork of your application
every time you open and close it, *even if you don't modify the file*.
Alpha still manages to coexist with build or make files because saving this
information does not change the modification date of the file. If the state
is set to "Think", neither the window position nor the current selection
are saved. If state is set to "None", no information is saved. The default
value for saved state can be changed by setting the Alpha variable
'savedState' to "mpw", "think", or "none". Note that if a given file
already has mpw information in it when the file is open, Alpha will always
update that information when the file is closed. Note also that "marks"
are always saved in the resource fork whenever a file is saved,
regardless of the setting of the 'savedState' variable.

The "Format" menus allows the way Alpha terminates lines to be changed.
The Mac uses a carriage return to mark the end of a line, Unix uses a
linefeed, and IBM uses both (of course). Alpha can read and write any of
these formats, and can convert between them just by opening a file,
choosing "Save As", and changing the selection in this menu. Note that if
you are going to be sharing files with a Unix or IBM machine, you
probably don't want anything in your resource fork, so you'd probably
want to set 'savedState' to 'none'.


          Menus

Alpha's menus are completely reconfigurable. Some of the menu items are
internal alpha commands, while others are Tcl procs defined in one of the
files of the "Tcl" subfolder. The following is an explanation of the
default menus. The explanations of items that are defined as Tcl procs are
implemented by the Tcl proc specified by "(proc <name>)", and can be found
in one of the .tcl files. All others are internal functions. Obviously you
don't have to worry about how the functions are defined if you don't want
to modify them.

Alpha uses Ramon Felciano's Mercury MDEF to display menus. In addition to
allowing other modifiers to be shown in the menu, this MDEF also allows
alternates, items that change depending on the state of the modifier keys.
Alternate items are tagged below by the modifier that must be pressed to
display it.

File
    New                      New file.
    Open…                   Open file.
    Recent…    (available if Recent Files Menu feature is active)
                            Menu of recently opened files. These same files
                            can be opened via the 'editFile' (cmd-') proc
                            of the filesets menu.
    Close                   Close file.
    Close All (option)        Close all files.
    Close Float (shift)        Close a palette.

    Save                       Save file.
    Save All (option)        Save all files.
    Save Unmodified (control) Save file without changing the modification
                            date.
    SaveAs…                   Prompt for name to same file under.
    Save A Copy As… (option) Save a copy of the open window.
    Rename To… (shift)        Rename file.

    Revert                   Revert to last saved version, throw away undo history.
    Revert To Backup (option) Revert to last backup copy, if any.

    Shell                   Start up command-line shell that interprets Tcl
                            commands. The shell has a few csh-type features,
                            such as 'ls', 'rm', etc. commands, as well as file
                            completion with the TAB key.
    Toolserver Shell (control) See here.
    Calculator (shift)        See here.

    Page Setup…               Set print options.
    Print (submenu available if Printer Choices feature is active)
        Print…                Print file directly.

        Kodex C Pretty Printer        Print through Kodex app.
        Enscriptor Fancy Printer    Print through Enscriptor app.
        Send PS to 'Drop•PS'        Print through 'Drop•PS' app.

    Print All…    (option)    Print all files.

    Quit                       Quit Alpha.

Edit
    Undo                    Undo.
    Redo (option)            Redo.
    Evaluate                Execute either the window or the selection as Tcl
                            source.
    Cut                        Cut selection to scrap.
    Copy                    Copy selection to scrap.
    Paste                    Paste from scrap.
    Select All                Select entire file.
    Select Paragraph (option)    Select current paragraph.
    Clear                    Delete selection.

    Twiddle                    Exchange characters bracketing the selection point.
    Twiddle Words (option)    Exchange words bracketing the selection point.

    Shift Left                Shift selection left one tab.
    Shift Left Space (option)    Shift selection left one space.
    Shift Right                Shift selection right one tab.
    Shift Right Space (option)    Shift selection right one space.
    Balance                    Select text out to the next set of matching braces.

    Emacs                    Lots of Emacs key bindings. Available if
                            Emacs feature is active.

Text
    Fill Paragraph            "Fill" paragraph that contains the insertion (proc
                            fillParagraph).
    Wrap Paragraph (option)    Break lines longer than 'fillColumn' in paragraph
                            containing insertion pt (proc wrapParagraph).
    Sentence Paragraph (option-shift) - Forces each sentence to start on new
                            line.
    Fill Region                "Fill" selection subject to 'leftFillColumn' and
                            'fillColumn', (proc fillRegion).
    Wrap Region (option)    Break lines longer than 'fillColumn' in selection
                            (proc wrapRegion).
    Sentence Region (option-shift) - Forces each sentence to start on new
                            line.

    Line To Paragraph        Convert a line to a paragraph.
    Paragraph to Line (option) Convert a paragraph to single line.

    Sort Lines                Sort selected lines (proc sortLines).
    Reverse Sort (option)    Sort selected lines backwards.
    Spellcheck Window        See here.

    Zap Invisibles            Delete all chars in file with ASCII code < 32, except
                            for LF, TAB and CR.
    Tabs To Spaces            Convert tabs to space runs.
    Spaces To Tabs (option) Convert space runs to tabs.

    Indent Line                Indent the current line.
    Indent Selection (option) Indent the selection

    Upcase Region            Upcase all chars in region.
    Downcase Region    (option) Downcase all chars in region.

    Strings
        Insert Prefix            Prepend string 'prefixString' to every line in
                                selection (proc insertPrefix).
        Remove Prefix (option)    Remove prefix string from lines in selection
                                (proc removePrefix).
        Insert Suffix            Append string 'suffixString' to every line in
                                selection (proc insertSuffix).
        Remove Suffix (option)    Remove suffix string from lines in selection
                                (proc removeSuffix).
        Set Prefix…                Change prefix string (proc setPrefix).
        Set Suffix…                Change suffix string (proc setSuffix).
    Comment Line            Comment out line, considering mode.
    Uncomment Line (option)    Un-comment line, considering mode.
    Comment Box                Create a comment box around selected text.
    Uncomment Box (option)    Remove such a comment box.
    Comment Paragraph        Comment out a paragraph.
    Uncomment Paragraph        Uncomment a paragraph.

    Goto Func
    Goto File Mark
    Mark Hilite                Select text last manipulated, such as from a paste.
    Named Marks
        Set…
        Goto…
        Remove…
        Sort
        Sort By Position
    Unnamed Marks
        Set…
        Exchange Point And Mark

Search
    Find…                    Present a search dialog.
    Search Start (option)    Return selection point to where the last search
                            started.
    Find Again                Search forward again with same settings.
    Find Again Backward (option)    Search backward again with same settings.
    Find in Next File        Restart multiple-file search in next file after
                            stopping at a match.
    Enter Search String        Use the current selection as the search text.
    Enter Replace String (option)    Use the current selection as replace text.

    Quick Find                Incremental search forward (grep, match words off,
                            ignore case on). Type chars to define string,
                            control-w adds the current word to the search
                            string, control-s/r search for the same string again.
    Quick Find Regexp (option)    Same as Quick Find but lets you use a regular
                            expression.
    Reverse Quick Find        Same think in reverse.

    Replace                    Replace the selection.
    Replace and Find Again    Replace the selection and search again forward.
    Replace All                Replace all of occurances of the search string
                            in the rest of the file.
    Replace in Fileset (control)    Global replace in fileset.

    Push Position            Push current pos onto a "stack".
    Pop Position            Pop last pos from stack and go to it.
    Goto Line                Goto specific line number.

Utils
    Compare
        Windows                Compare top two windows, sending output to a third.
                            Selecting a line in the third window and hitting
                            return (or enter) moves that line to the top of
                            the window.
        Files                Same as above, but prompts for files.
        Directories            As above, but works for entire directories.
    File Utils
        File Remove…        Remove a file.
        File Info…            Display/edit info about a file.
        Text to Alpha        Set creator a text files to Alpha.
    Win Utils
        Insert Path Name…    Prompt for a file and insert complete pathname in
                            window.
        Insert File…        Insert the text of another file.
        Word Count            Count lines, words, chars in window (proc wordCount).
    Ascii Etc
        Quote Char            Wait for key press and insert key.
        Key Code…            Wait for key press and insert keycode and modifier
                            string suitable for key binding.
        Key Ascii…            Same as above, but use ascii form.
        Get Ascii…            Display ascii code for char to right of insertion.
        Insert Ascii…        Prompt for ascii code and insert character.
    Matching Lines            Find all lines that match a regular expression and
                            summarize in new window. (proc matchingLines).
    Goto Match                Jump to the original text specified by the current
                            line in a "Batch Find" or "Matching Lines" window.
    Next Match                Next match.
    Send URL                Send selection as URL to proper internet app.
    Cmd-Double Click        Look up and display definition of the selected
                            word. If in "C" or "C++" mode, use the file pointed
                            to by 'tagFile'. If in "Tcl" or "Shel" mode, look
                            in "Alpha Commands", "Tcl Commands", and the "Tcl"
                            subfolder.

Config
    Current Mode
        Menus and Features…    Change current mode's menus and features.
        Preferences…        Change options for current mode.
        Edit Prefs File        Edit mode-specific preferences.  Loaded
                            after mode entered for the first time.
        Load Prefs File        Load current mode's preferences.
        Describe mode        Describe current mode's variable settings and
                            bindings.
        Change…                Change the current mode.

    Global
        Menus and Features…    Change global menus and features.
        Preferences>        Global variables.
        Edit prefs file        Put your own arbitrary startup code here (used to be
                            "userStartup.tcl"). Loaded after all standard Tcl
                            code.
        Special Keys…
        List Global Bindings Create a new file containing all current global
                            key bindings.
        List Packages
        List All Bindings    Create a new file containing all current key
                            bindings.
        List Functions        List all functions currently defined, both
                            "core" functions (those coded in C), and those
                            coded in the supplied Tcl files.
        Rebuild Package Indices

    Suffix Mappings…        Displays and allows editing of suffixes (really
                            filename patterns) for all existing modes.
    Packages->                Download updated versions of Alpha or any packages
                            from one of Alpha's ftp/www sites.
    Helper Apps…
    Describe Binding…        Wait for a keystroke, then display that keystroke's
                            binding.
    View Saved Settings…     Any variables or flags that you modify during
                            the course of a session are saved to files in the
                            system preferences folder when Alpha quits.
                            This function shows all such saved variables.
    Remove Saved Settings…    This function allows settings to be removed.


    Set Font Tabs…            Change font and/or tabs for current file.
    Redefine Colors->        See Colorizing.

Wins (an icon with three windows)
    Zoom                    Zoom windows in and out.
    Single Page (option)    Resize as single page.
    Choose A Window            Choose window to select from list (proc
                            chooseAWindow).
    Iconify                    Toggle iconification of front window.
    Arrange                    Rearrange open windows.

    Split Window            Split window into two panes, or unsplit.
    Toggle Scrollbar        Toggle the horizontal scrollbar on the frontmost
                            window. The scrollbar can be enabled/disabled on
                            subsequent variables by changing the value of
                            the 'horScrollBar' flag.



          Menus, User-Defined

All of Alpha's menus are defined in the initialization files that Alpha
loads on startup.  They can be altered or discarded at well.  Alpha's menu
commands allow the the user to build custom menus which contain names of
functions, macros, or arbitrary TCL commands that just HAVE to be in the
menus, as opposed to being merely callable through the bindings.  The
syntax is dead simple.  Menus can be nested, allowing hierarchical menus to
be defined.  See the 'alphaMenus.tcl' file for examples.  The following meta
characters can be embedded in the strings:

   Meta-character     Usage
   --------------     -----

    ; or Return       Separates multiple items.
    ^                 Followed by an icon number, adds
                      that icon to the item.
    !                 Followed by a character, marks the
                      item with that character.
    <                 Followed by B, I, U, O, E, or S,
                      sets the character style of the item.
    /                 Followed by a character, sets up
                      a keyboard equivalent.
    (                 Disables the item.


The following modifiers can be used to require other combinations of modifiers
than just the command key. Control-option, for instance, is specified by
putting the string "<B<I" in the menu item. The menu symbol for shift is
an upward outline arrow, control is the outlined ^ symbol ("Wins:Iconify"
has one), and option is the wavy line with the dot in the upper right
("File:Close All" has one). The following are characters that can follow
the '<' and what they signify.

    B        - control key required
    I        - option key required
    U        - shift key required (only for alpha-numerics!)
    O        - command key required
    S        - isDynamicItem is part of dynamic item.
    E        - forces item to start new dynamic item.


A '/' followed by a character in the left column sets up a keyboard
equivalent for the key in the right column:

    a    Enter            n    F10
    b    Return            o    F11
    c    Tab                p    F12
    d    Num Lock        q    F13
    e    F1                r    F14
    f    F2                s    F15
    g    F3                t    Help
    h    F4                u    Del
    i    F5                v    Forward Del
    j    F6                w    Home
    k    F7                x    End
    l    F8                y    Page Up
    m    F9                z    Page Down


The menu creation syntax is :

    Menu [-s] <-n name> <-i num> [-p procName] [-m] [-M <mode>] "Tcl list of items"

Where the arguments have the followings meanings:
  '-s'            Use system menu definition proc (faster).
  '-i <num>'    Resource id of icon suite to use for menu title.
  '-n <name>'    Name of menu.
  '-m'            No menu form. If not supplied, each menu item is split into
                  words at each capitalized letter.
  '-p <pname>'     Rather that having alpha call a Tcl proc named by the menu
                  item's text, this option tells Alpha to call the tcl proc
                  named by 'pname' with two arguments: the menu name, and the
                  text of the menu item chosen.
  '-M <mode>'    Bindings only take effect in specified mode.

Once the menus are created, they can be inserted and  deleted from the
menu bar by the syntax:

   insertMenu "name"
   removeMenu "name"

as well as through macros.


As alluded to above, Alpha attempts to make procedure names readable in the
menus by separating words at any capitalized letter. For example,
'findFile' becomes "Find File". This function is turned off by the '-m'
option.

Menu items can be enabled and disabled through the TCL command
'enableMenuItem'. Menu items checkmarks can be turned on and off via
'markMenuItem'. Menu items can be appended via 'addMenuItem' and deleted
via 'deleteMenuItem'. See the "Alpha Commands" help file for syntax.

As explained above, the Mac ToolBox uses various keys to specify text
style and key equivalents. Sometimes you may want these characters
included in your text literally. If an ampersand ('&') is the last
character in a menu item, Alpha coerces the string so that these special
characters are not interpreted.

If an ellipsis ('…') is the last character in a menu item (except possible
for the above ampersand), it is stripped off before searching for the
function corresponding to the chosen item.


#================================================================================
# Just for the heck of it, the following is a script that I put in my
# prefs.tcl file. It creates a menu for all the .tex files in my
# thesis folder, minus the dirname and .tex extension.
#
set THESIS "Internal:Textures:thesis"
proc thesisMenuProc {menu item} {
    global THESIS
    edit -r -m $THESIS:$item.tex
}

set files ""
foreach f [glob $THESIS:*.tex] {
    lappend files [file rootname [file tail $f]]
}
menu -n Thesis -m -p thesisMenuProc $files
unset files
#================================================================================



          TCL

See the Tcl manual page under the 'Help' menu for a complete description of
Tcl, the Tcl shell, and its commands.  Each of the Tcl commands and
several sections have a mark defined, so you can use the "Mark" menu to
navigate through the manual page.



          Key Bindings

Any TCL command can be bound to any single keystroke. One way to bind a
function is with a statement such as:

      Bind 'c' <modifier string> funcName [<mode>]

where c is a character, <modifier string> is an optional string containing
one or more of:

      c   - command modifier
      o   - option modifier
      s   - shift modifier
      z   - control modifier
      e   - escape modifier

Additionally, the modifier string can contain a capital letter specifying
that the binding is only activated if preceded by control and the lowercase
version of that letter. This feature allows multiple-key combinations ala
Emacs. The following line binds cmd-shift-f to the function 'forwardChar':

 Bind 'f' <cs> forwardChar

The next line would bind the same function to C-x C-f, assuming that
control-x is bound to the function 'prefixChar':

 Bind 'f' <cX> forwardChar

'mode' is an optional parameter that specifies, when present, that the
binding is only active in a given mode. Note that given a general binding
(no mode specification) and a binding specific to the current mode, the
last binding to have been created is the one found first.

Additionally, most keyboards have keypads and/or Function Keys. These
keys can be bound using case-insensitive numeric labels using the same
bind command as above, with the label replacing the character. For
example, to bind F1 to function 'funcName', the following would work:

    Bind F1 funcName

As above, the binding can include a modifier string. The following labels
are defined for US keyboards:

  Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 Help Home Pgup Del
  End Pgdn Left Right Up Down Clear Kpad0 Kpad1 Kpad2 Kpad3 Kpad4 Kpad5
  Kpad6 Kpad7 Kpad8 Kpad9 Kpad= Kpad/ Kpad* Kpad- Kpad+ Enter Kpad.

The menu item 'Config:Global:List All Bindings' will list all of the
bindings currently in effect in a format suitable for re-loading.

The above labels may not be sufficient for all keyboards (attention
international users). If a hex number is used instead of a character inside
the single quotes, the binding is done to key codes instead of ascii
values. The following is a key code version of the same binding:

      Bind 0x03 <cs> forwardChar

The key code for any given key can be obtained by using the menu item
'Utils:Ascii Etc:Key Code'.

Also, there is an alternate form that allows the specification of an
ascii code directly:

    ascii 0x20 <z> setMark

Binds control-space to 'setMark'.

Note that menu item command equivalents take precedence over bindings, and
that the 'Bind' command does not affect the command equivalents displayed
in the menus. Also note that key code bindings take precedence over ascii
bindings.

Finally, there are 'unBind' and 'unascii' functions, with identical
arguments to their counterparts.



          Undo + Redo

Alpha supports unlimited undo and redo. This means that most changes can
be undone, and then redone, at will. Bear in mind that once you create new
modifications, all changes that you have undone but not redone are lost.
Another point to bear in mind is that saving a buffer to disk currently
flushes the undo buffer.


          Event Hooks

Alpha calls the TCL procs "openHook", "saveHook", "saveasHook",
"savePostHook", "closeHook", "activateHook", "deactivateHook",
"suspendHook", "dirtyHook", "quitHook" and "resumeHook" when the
corresponding events occur. With the exception of "saveasHook", the proc
are all called with the complete pathname as the sole argument.
"saveasHook" is called with the old pathname as the first argument and the
new pathname as the second argument. Default implementations for these
commands are in the file 'alphaHooks.tcl'.

You can add to these hooks by registering procs to be called when the
hooks are called. This is done by adding a line like this to your prefs
file:

      hook::register 'hook-name' 'your proc' 'mode' ?... 'mode'?

Here are three examples:

      hook::register savePostHook codeWarrior_modified "C++" "C"
      hook::register savePostHook ftpPostHook
    hook::register saveasHook htmlLastModified HTML

If you don't include a 'mode', then your proc will be called no
matter what the current mode is.   Avoid this unless absolutely
necessary.


          Tags

Alpha supports the use of tags to find declarations of functions; by
default this is set up only for 'C'.  When searching for a tag, Alpha looks
for the tag file specified by the "tagFile" string variable.  Alpha's tag
generating routines use the regular expression in the string variable
"funcExpr" to look for function declarations.  In other words, we don't
parse the text.  If you declare your functions differently, you can change
"funcExpr" to suit your own style.  Alpha currently uses the following
regular expression to find C function declarations:

              ^[^ \t\(#\r/@].*\(.*\)$

Although complicated, this expression makes sense if you slowly wade
through it. The string that we are looking for must take up an entire
line. It must begin with a character other than '\t', '#', '\r', '/', ' ',
'(', or '@'. There must be a set of parenthesis.

Note that not only can you customize this to your style of 'C'
declarations, you could also use it to generate tags for other languages.
The only thing you need to bear in mind is that the tag routines use the
complete word previous to the first '(' in the selected line as the
function's name. If there is no '(' in the selected line, the last word in
the line is used. Therefore, Pascal procedures with or without parameters can be
identified.

Caveat: Apple's list manager can't handle more than 32k of text in the
entire list, so there is a practical limit of 2000 or so tags in your
project.


          Backups

If the 'backup' variable is set in the "Config:Global:Preferences:Backups"
dialog, Alpha backs up each file before saving new modifications. By
default, the backup file is in the same folder, and its name is formed by
suffixing a tilde to the name of the saved file. Backups are actually
performed in the 'saveHook' proc (see above), in the file alphaHooks.tcl. The
Tcl variables 'backupFolder' and 'backupExtension' can be used to modify this
behavior.


          Fill Routines

The "fill" and "wrap" routines reformat text to specified line lengths.
This is useful in two case. First, word processors such as Microsoft Word
only insert carriage returns at the end of paragraphs. Secondly, while
typing and inserting text into pre-existing paragraphs, the line lengths
become unequal.

The "wrap" routine handles word processor documents quickly by merely
inserting carriage returns as necessary to ensure all lines in the
selected region are shorter than specified by the variable 'fillColumn'.
Alpha asks the user if wrapping should be done whenever the user opens
files that have lines longer than 'paraColumn' characters. This feature
can be defeated by including the word 'nowrap' anywhere on the first line.

The TCL routines 'fillRegion' and 'fillParagraph' go further. Not only do
they break lines, but they also coalesce lines to eliminate short lines.
Both routines work by stripping the relevent text of white space, then
re-inserting white space and carriage returns so that no line extends past
'fillColumn' characters in length and begins with 'leftFillColumn' spaces
characters. Both routines are implemented in the file 'textFill.tcl', and
therefore different definitions of paragraphs can be accomodated by
modifying the appropriate TCL procedures.


          Soft Text Wrapping

"Soft" text wrapping is re-formatting the rest of the paragraph on-the-fly
as text is inserted and deleted. Soft-wrapping is enabled by selecting
"Soft" in the wrap popup menu in the status bar. The text to be wrapped is
delimited by the current line and the last line in the current paragraph.
Wrapping occurs after insertions that result in the current line becoming
longer than 'wrapHigh' characters long (tabs counted as one character), or
deletions where the length of the line (tabs likewise) becomes less than
'wrapLow' characters long.


          Word Breaking

Alpha allows you to redefine its internal notion of what a word is,
through the variables 'wordBreak', and 'wordBreakPreface'. 'wordBreak' is
set to a regular expression that defines a word to you. 'wordBreakPreface'
should be a regular expression that matches exactly one of any characters
that are not in your word definition.

For instance, the default definition of 'wordBreak' is '\w+'. This matches
any contiguous sequence of contiguous alphanumeric characters.

The default value for wordBreakPreface is '(\W)', basically just
the negation of any any of the characters in your 'wordBreak' definition.

The need for both these variables in backward searches can be seen as
follows. Suppose your window's text is "hey hello", and the current
insertion is between the two 'l's. Now, searching backwards for the above
'wordBreak' definition will take the insertion to between the 'e' and the
first 'l', not really where we want to say is the start of the word. By
contrast, if we search backwards for 'wordBreak' and 'wordBreakPreface'
concatenated together, and then move forward one character after a
successful search, we end up right before the 'h' in 'hello', just where
we want to be.


          File Sets

File Sets are lists of files that Alpha uses for multiple-file searches and
tag searches, among other things.  Typically, a user will set up several
different file sets, perhaps one specifying all the source files in a
project, another specifying all the Mac include files, and another
specifying all the UNIX include files.  When a command using file sets is
initiated, Alpha evaluates the command "getCurrFileSet", which returns a
list of complete pathnames to search.

Functions that use file sets operate on the "current" fileset, which is
specified by the 'currFileSet' variable.  The current file set can also be
switched by using the "File Set" hierarchical menu.  There is also a flag
'Auto Adjust Fileset' which will switch filesets whenever the fileset menu
is used to open a file.

Selecting any item from the fileset menu opens that file.  If the flag
'Include Non Text Files' is set, the fileset menu may contain files Alpha
is not designed to open; these are sent to the Finder which will open them
using whichever application created them.  A common use of this feature is
a hierarchical fileset containing a complete C or C++ project.  Selecting any
project source file will open that file for editing, and selecting the
project file/debugging symbol file/... will open that using appropriate
tool (Symantec Project Manager or Codewarrior IDE or Debugger,…)

AlphaLite has no fileset utilities menu, allowing just for the creation and
deletion of filesets.

Fileset Utilities
=================

The fileset utilities menu contains the following items:

New Fileset…          -- create a new fileset of one of the following
                        six standard types (others may be added by
                        writing your own Tcl code. see "filesetsMenu.tcl"
                        and "latexFilesets.tcl" for details):
                            Codewarrior
                            FromDirectory
                            FromHierarchy
                            FromOpenWindows
                            Ftp
                            Procedural
                            Tex
                            Think

Delete Fileset…      -- remove a fileset, permanently if desired.
Update Current Fileset -- re-build a fileset from scratch
Update A Fileset     -- (hold down option) lets you choose a fileset to
                        rebuild.
Rebuild All Filesets -- total menu rebuild.
Zap And Build Filesets -- (hold down option) a more drastic version of the above
Choose                  -- a hierarchical menu from which to set the
                        current fileset.
Hide Fileset          -- if you have many filesets, some of which are only
                        used for searching purposes, you can remove them
                        from the menu.
Fileset Flags         -- See below for an explantion of the flags.

Find Tag              -- see 'Tags' for information on this and the
                        following item.
Create Tag File


Browse Fileset…      -- opens a window containing all fileset items,
                        from which any can be opened.
Close Entire Fileset… -- close all windows which belong to a given fileset.
Fileset To Alpha…     -- convert all text files in a fileset to Alpha's creator.
Open Entire Fileset… -- open all files in a fileset
Open Fileset Folder… -- tells the Finder to open the base folder which
                        contains a fileset.
Rename Fileset…      -- change a fileset's name
Replace In Fileset…  -- global search and replace in all files. Use this
                        item with care!
Stuff Fileset…           -- If you have 'DropStuff' installed, you can archive a
                        fileset.
Word Count              -- Count all words in a fileset
Word Count Fast         -- A quicker version which seems to have a memory leak!

The following flags may be set:

Auto Adjust Fileset      -- opening a file from the menu will adjust 'currFileSet'
Include Non Text Files     -- files not of type 'TEXT' may be in the menu.
Indent Fileset Items     -- visually format submenus if appropriate.
Sort Fileset Items       -- force alphabetical ordering for all filesets
Sort Filesets By Type      -- structure the fileset menu in a user-defined, type-
                        dependent fashion; see Personalisation.

Fileset Types
=============

'From Directory'     -- The basic type: create a fileset of all files in a
                        given directory which match a given pattern.

'From Hierarchy'     -- Takes the above one step further and allows filesets
                        to include all files in a nested set of folders.

'From Open Windows'  -- Make a fileset containing all currently open windows.

'Codewarrior'         -- Query the Codewarrior IDE for a list of all files in
                        the current project.

'Think'                 -- Query the Symantec Project Manager for a list of all
                        files in the current project.

'Tex'                 -- Make a fileset of all parts of a multi-part TeX/LaTeX
                        document.  Alpha's LaTeX mode understands these and
                        will automatically send your TeX application the base
                        .tex/.ltx file when you select 'Typeset' on any
                        component part.

'Ftp'                 -- documentation missing…

'Procedural'         -- documentation missing…

The following items will be added to the utilities menu if you use
TeX filesets:

ExtractEpsBoxSizes   -- search all document parts for included eps graphics,
                        extract bounding box information from the .eps files
                        and insert it explicitly into the document (can lead
                        to much quicker typesetting).
DeleteEpsBoxSizes    -- remove all the above bounding box information
HierarchicalBibFiles -- bibliography files may \input others, so they should
                        be searched (the default is not to do this, because
                        .bib files may be enormous).

Personalisation
===============

As well as adjusting the aforementioned flags, the fileset menu allows
complete user control of the structure of the menu in the following way:
Set the 'Sort Filesets By Type' flag, and set the variable
"filesetSortOrder" as follows:

   The structure of    this variable dictates how the fileset
   menu    is structured:

       '{pattern p}'
           lists all filesets which    match 'p'
       '-'
           adds    a separator    line
       '{list of types}'
           lists all filesets of those types.
       '{submenu name sub-order-list}'
           adds    a submenu with name    'name' and recursively
           adds    filesets to    that submenu as    given by the
           sub-order.

   Leading,    trailing and double    separators are automatically
   removed.

For example, the default value of this variable (more as an example than
anything else) is:

set filesetSortOrder { {pattern System} {pattern User} {pattern Preferences} \
                        - {tex} - {pattern *.cc} \
                        {submenu Headers {pattern *.h}} \
                        - {fromDirectory think codewarrior \
                        fromOpenWindows fromHierarchy} * }

You can and should over-ride this in your "prefs.tcl" file (copy and paste
from here, then make your changes).


          Macros, Keyboard

If you activate the Macros feature Alpha supports keyboard macros which
record a sequence of keystrokes to be played back later with the function
'Execute Keyboard Macro' or written into a buffer by selecting 'Dump Macro'.
The dump function prompts you for a macro name, which must consist only of
letters of the alphabet, digits, and '_'.

These macro declarations can then be edited, loaded, and bound to
keystrokes.  Loading a macro or a binding is accomplished by hiliting the
text and selecting the "Evaluate" item of the 'Edit' menu.  If no text is
hilited, the entire window is loaded by the same command.  Macros can be
bound to keys in exactly the same manner as functions (see above).


          THINK and Alpha

Yes! Finally Think has support for external editors (7.0 or better).  To
make this work, put an alias of Alpha in the "Tools" subfolder of the
folder the project manager is in, and name the alias "Editor".
Secondly, check the "Use External Editor" button in the project manager's
option dialog.  You do not have to check the "Always Check File Dates"
button.

Any open window events will now be vectored to Alpha, and from within
Alpha you can initiate compiles, disassembles, makes, etc. Errors are
reported back to Alpha.

Look in :Tcl:Menus:"thinkMenu.tcl" for the code controlling much of the
interactions between THINK and Alpha.  If you improve anything, please send
it back to me.

If a window contains a file that is part of the a project that is
currently open in the Think Project Manager, selecting "Open Header" from
the Think menu will put up a list of include files. The same files can be
accessed by option-clicking on the window's title-bar.

A fileset consisting of the source to a think project can be created
through the "File Sets" menu.


          Rectangular Editing

If the option key is pressed while the mouse is dragged,  a rectangular
section of text is selected instead of the normal selection. This
rectangular selection may extend over multiple lines, but contains only
text between the column of the drag start and the column of the drag end.
The drag cannot end on a column or row less than the start. This selection
can be extended by option-shift-mouse, but not dragged further.

The rectangular selection can be deleted, copied, and pasted. This is very
useful for tables and arrays, such as in LaTeX. Usually, the operation
will be intuitive. However, if you use proportional fonts the selection
may appear ragged. If some of the line contain tabs, the result may not be
want you want. Converting tabs to spaces in the desired region before
attempting rectangular selection usually fixes the problems.

The most natural semantics of rectangular selection aren't obvious. I
chose to implement it in a similar fashion to that of Microsoft Word.
Preditor does it in another way, and has many bugs (and it's  commercial,
hah!).



          System Software 7.0

Alpha is 32-bit clean and high-level event aware.

Under 7.0, Alpha uses temporary memory to accommodate large files. This
allows you to open multi-megabyte files even when Alpha's partition is set
only at 512k, if the system has that much memory available. Note that
using temporary memory makes that much memory unavailable to other
applications. Contrary to all admonishments, Alpha does not unlock
temporary memory across WaitNextEvent calls and may eventually use all the
memory in your system. You can turn this feature off through 'tempMem'.

Note, however, that the clipboard is allocated by the system in Alpha's
heap, and therefore cannot take advantage of temporary memory.




          Apple Events

See the Help file on AppleEvents.


          MPW

Alpha's 'dosc' capability (see the function "dosc") can be used to send
events to MPW's ToolServer. Using about ten lines of C code and the ~40
lines of Tcl code in 'mpw.tcl', I created a pseudo mpw shell (look under
the "File" menu). This shell uses Alpha's 'dosc' function to package each
shell command up into an Apple Event and send it to the ToolServer, which
then evaluates the command and returns the result to be displayed in the
shell. I'm rather new to Apple Events and the ToolServer, so there are
probably a few rough edges.

If anyone has extensive docs for ToolServer I'd appreciate looking at them.
I only have the application because I am a beta tester for another product
that supports ToolServer. I was given the application for the beta testing,
but not any docs. And of course, I can *not* give away copies of
ToolServer because it is a licensed Apple product.

Finally, Tom Moertel ([e-mail]) has written and provided a set
of tools that make life easier while writing code in Alpha for the MPW
environment. The tools make extensive use of Apple Events, so you must be
using MPW 3.3a or greater. (Earlier versions cannot receive commands via
Apple Events.)

  With the MPW-Alpha package you can:

    o  Send TCL commands to Alpha from MPW
    o  Use MPW 411 from Alpha for instant access to programming help
    o  Automagically locate source code errors from your last MPW compile
    o  Use the MPW CDent tool to reformat (grind) C/C++ source code
       from within Alpha

This package is available via anonymous ftp from cs.umd.edu.


          File Formats

Alpha reads and writes files stored in three (or maybe four) different
formats. The three main formats are mac (lines end with a carriage
return), unix (lines end with linefeed), and IBM pc (lines end with both
carriage return and linefeed. Typical, isn't it?).

Alpha will transparently read and write all three of these formats. You
don't have to do anything special to use different formats, but the
'SaveAs...' dialog allows you to specify the format that a file is written
in through the 'Format' button.

The fourth file format is just a modification of the ordinary mac format.
Word processors such as Microsoft Word and MacWrite only put carriage
returns at the end of paragraphs, so that they can wrap  the paragraphs on
the fly. This is what is referred to as 'paragraph format' in the rest of
the help text. Alpha does not transparently convert to and from this
format because there are valid reasons why someone might want to edit a
paragraph formatted file while not in paragraph mode.

Therefore, when Alpha detects reads a paragraph-mode file, it asks the
user whether or not to remap it. Files can be mapped back to paragraph
mode by setting 'fillColumn' to a very large number and executing
'fillRegion' on the text.

          Printing

If you activate the "Printer Choices Menu" feature Alpha has many printing
options available. Printing is accomplished via a submenu under the File
menu. The menus allows printing either via Alpha or several other
applications.

If printing through alpha, the variables 'printHeader', 'printHeaderTime',
and 'printHeaderFullPath' control whether and what type of header is
printed at the top of each page. These flags are actually used in the procs
'printLeftHeader' and 'printRightHeader' (in clickUtils.tcl) to create the
string that appears on the left side of the top of the page. 'leftMargin',
'topMargin', and 'bottomMargin' control margins on the printed page.

'printerFont' and 'printerFontSize' allows the size and type of the
printed font to be specified.

The external apps that Alpha is currently configured to use are
"Enscriptor", an app that allows multi-column and other options, "Kodex",
a "C" pretty printer, and "Drop•PS", which prints postscript files. All
options operate on the frontmost window. These applications are not
supplied with Alpha, but can be downloaded from any comprehensive mac site.
They can also be downloaded from Alpha's home site. "Enscriptor" and
"Kodex" are shareware apps written by John Cho. "Drop•PS" is a freeware
app written by some evil commercial text editor guru :-).


          Random Tips

- When a window is "dirty" (has unsaved changes), a
  red disk icon appears just below the titlebar in the
  upper right corner of the window, and a diamond
  appears next to the corresponding item in the Windows
  menu.

- All dialogs that have editable text can use the Cut,
  Copy, and Paste menu command equivalents.

- In all dialogs, non-editable controls can be selected
  by typing Command-<first char of control>. If there
  are no editable controls in the dialog, simply typing
  the first letter of the desired control suffices. PgUp,
  PgDown, Home, and End keys now work for most list dialogs.
  Popup menus can be navigated with the up and down arrows.

- Set the flag 'undoOn' to 0 in order to speed up long
  replace-all and macro modifications.

- After a piece of text has been yank'd or paste'd, the
  'mark' is set to the beginning of the new text and the
  selection is at the end. 'markHilite' will now hilite
  the entire insertion. This is especially useful when
  moving code. Cut the code, insert at a new position,
  select the inserted text by selecting "Text:Mark Hilite", and
  then use "Edit:Shift Left" and "Edit:Shift Right" to move
  the text to the proper indentation.

- Most help files have marks in them, which let you quickly
  navigate to places of interest. You can access these marks
  by command-clicking on the title-bar or on the "M" icon
  above the vertical scrollbar.



          Variables

There are two different kinds of variables in the Alpha world: global vars
and mode vars. Mode vars can have different values in each mode, and are
modified by the "Config:Current Mode:Preferences" dialog. Changing one of
these variables changes the variable's value for all windows of the current
mode.

Global variables are accessed via the "Config:Global:Preferences" dialog.
Changing one of these variables affects all windows.

Alpha records which variables are modified in the course of a session and
saves them prior to quitting.

This list is incomplete. Click Help in the prefs dialog for more help.

Mode Vars

autoMark       • Automatically mark windows on open if they don't have marks.
fillColumn     • Number of columns use as limit for
                 "fill" routines. See 'leftFillColumn'
funcExpr       • Set to the regular expression that
                 Alpha uses to find function
                 declarations.
leftFillColumn • Number of blanks left at beginning of
                 lines by 'fill' routines.
parseExpr      • Set to the regular expression used by parseFuncsAlpha to
                 extract the name of a function from the text returned by a
                 search for funcExpr.
wordBreak       • Regular expression used to defines words for all internal
                 operations.
wordBreakPreface • Prepended to 'wordBreak' when looking backwards for a
                 word. See the "Word Break" section of this file for more
                 information.
wordWrap       • if true, lines exceeding 'fillColumn'
                 in length are automatically wrapped
                 during normal text insertion (typing)
wrapBreak       • Reg expr used for automatic word wrapping.
wrapBreakPreface • Reg expr used for automatic word wrapping.

Global Vars

autoHScroll       • Automatically scroll horizontal scrollbar
                 to follow insertion.
autoSave       • If TRUE, buffers (except untitled buffers) are automatically
                 saved every 'changesLim' changes.
backDir           • folder in which to store backup files.
backExtension  • Suffix to append to backup files.
backup         • if TRUE, the default Tcl proc 'saveHook' makes a backup
                 of a file before the data is written. The default backup
                 scheme has extension "~".
blinkCursor    • Cursor blinks
blockCursor    • if true, Alpha uses a block cursor instead of a vertical
                 line.
bottomMargin   • Bottom print margin.
changesLim     • number of changes to a window before
                 garbage collection or autosave is done.
coloring       • enable keyword coloring.
def{Height,Left,Top,Width} • If 'fullScreen' set, default size
                 of windows.
defaultFont    • font to use on new windows and files
                 which don't have associated font
                 specification resources.
doubleSpaces   • If true, fill routines end all sentences with double spaces.
dragAndDrop       • Enable drag and drop.
fontSize       • Default size of fonts used to display
                 files.
forceMainScreen• If true, forces windows to main screen. Useful if you
                 have a small screen and windows habitually are too large.
horScrollBar   • If set, use horizontal scrollbar.
iconifyOnSwitch• Iconify all windows when suspending.
infoWindowsDirty• Dirty/Clean state of description windows.
intelCutPaste  • Enable intelligent cut and paste.
lockStatus       • Disable status window dragging.
moveInsertion  • if true, 'pageBack' and 'pageForward'
                 move the insertion point
numWinsToTile  • specifies the number of windows tile
                 commands should affect.
paraColumn     • Alpha automatically wraps files
                that contains lines longer than this.
powerThumb       • If true, vertical scrollbars have power thumbs.
printerFont       • Font to print documents.
printerFontSize• Size to print documents.
projectorAware • Respect projector resources.
savedState       • set to either "mpw", "think", or "none" depending on how
                 much information you wish Alpha to save in the resource
                 fork of the files you edit. See the "Files" section of
                 this file for more information.
showInvisibles • Show spaces, tabs, crs.
sortColumn     • column to use for sort routine.
sortedIsDefault• if set, sorted is the default for
                 function and section menus.
sortFuncsMenu  • Whether or not to sort the funcs menu.
tagFile        • complete path-name of tag file
tearoffMenus   • toggles tear-off menus.
tile{Height,Left,Top,Width} • rectangle to tile windows
                 within.
tempMem        • Enable use of system temporary memory.
undoOn         • used to turn undo on and off. When undo
                 is turned off, all undo info is lost.
                 Useful when doing global replaces, etc.
wrapHigh       • Line length limit beyond which soft-wrapping occurs, if
                 enabled.
wrapLow           •      ""            ""


          Spellchecking

Alpha has the capability to interact with the spell-check 'Excalibur',
written by Robert Gottshall and Rick Zaccone.  The menu item 'Spellcheck
Window' is always available in the "Utils" menu.  Selecting this item will
start up Excalibur and send an OpenDoc event describing the current window.
For version 1.4 and earlier, if Alpha has to launch Excalibur you will need
to dismiss Excalibur's opening dialog by hitting the Cancel button.
Subsequent selections of the menu item will switch right into Excalibur
with the correct file displayed.  In future versions, this will become even
more automatic.

Excalibur is free, but not in the public domain.  It can be obtained from
all the usual Internet ftp sites, as well as cs.umd.edu under
pub/faculty/keleher/Alpha.


          International Users

There is a basic problem international users will notice, which have to do
with the fact that the keyboard layout is different in different countries.
Therefore some keybindings in Alpha may not work with all keyboards. For
example, on a Swiss keyboard, '/' is shift-7 (which means you have to press
shift to get '/'. This means there is no difference between cmd-/ and
shift-cmd-/ on such a keyboard. In Alpha these are bound separately to
'zoom' and 'singlePage'.

If you're using a western keyboard Alpha can solve this problem for you.

First: Activate the internationalMenus feature.  It replaces some
keybindings in the menus and solves problems like the one just described.

Second: Tell Alpha which keyboard layout you're using in the prefs dialog
Config:Global:Preferences:International. (In a future version, Alpha should
be able to get this information from the OS directly.) This will make sure
that also bindings not defined in the menus work, e.g. that the electric
braces work.

If you're not using a western keyboard or if you do encounter any problems,
reading the following section will help to clarify things and should help
you to fix the problem.

To solve the problem with bindings in the menus you can use the
menu::replaceWith command. To solve the problem with the Swiss keyboard
described above you would add the following to your prefs file:

    menu::replaceWith winMenu [list "//<Szoom" "//<S<I<OsinglePage"] \
        items "<S//zoom" "<S<O<U/=singlePage"

To define your keyboard layout, add a line like this to your prefs file:

    set "keyboards(U.S.)" {
     {§1234567890-=[];'\`,./}
     {±!@#$%^&*()_+{}:"|~<>?}
     <U/[
     <U/]
    }

which contains four strings which Alpha uses to set these internal
variables:

    keys::mapShiftBindFrom "`1234567890-=[]\;',./"
    keys::mapShiftBindTo   "~!@#$%^&*()_+{}|:"<>?"
    bind::leftBrace <U/[
    bind::rightBrace <U/]

which tell Alpha how to map using the 'shift' key.  Therefore on
an American keyboard, shift maps each item in the upper string into
the corresponding item in the lower string.  Set these strings up
and then any bindings you set will work ok.

See the file alphaDefinitions.tcl for examples of keyboard layout
definitions.

If you define an array entry keyboards(my-country), then you can just
select that in the international prefs dialog, and Alpha will set the
flags correctly.  You can then send that keyboard array entry to the
ALPHA-D mailing list (see Readme for details) for inclusion in a
future version of Alpha.

If any other package defines bindings which depend upon these
variables, you will need to restart Alpha after messing with the variables.
If a package wishes to be told when the keyboard changes, it can do
that by registering with the 'removekeyboard' or 'keyboard' hooks like
this:

    # tell me when we switch to a "Swiss German" keyboard
    hook::register keyboard keys::swiss "Swiss German"
    # tell me when we disable a keyboard
    hook::register removekeyboard my_disable_proc
    # tell me when we enable a keyboard
    hook::register keyboard my_enable_proc

In this way a clever package could remove the need for restarting
Alpha by unbinding and then rebinding all necessary items.

          Drag and Drop

Alpha supports drag and drop cut, copy, clear, and paste. To use this
feature, select some text, then move the cursor over the selected text.
The cursor should then turn into an open hand. Mouse down, and move the
cursor to the place you wish to paste the text. When the mouse is
released, the hilited text is moved to the new location.

Option-mouse does a "copy" instead. You can also drag selections between
windows and to and from other applications, including the finder. Text
can be deleted by dragging it to the trash can.

You MUST have system 7.5 or above or Apple's "Macintosh Drag And Drop"
installed. Get a copy from Apple or via Alpha's web page.



          Status Bar

The stripe across the bottom of the screen is a floating window that
displays status information, certain prompts (option-x, and see the func
'statusPrompt'), and the current row and column.

You can't make this window go away. However, both 'sizeWin' and 'moveWin'
accept "StatusWin" as a window specification and will act on this window,
so you can move the window offscreen if you really wish. The height
parameter to 'sizeWin' is ignored.

The status bar can be dragged if the flag 'lockStatus' is turned off.

Clicking over the row and column indicators allows you to jump to a
particular line.

The left-most popup menu allows you to choose the type of wrapping when
typing.

The second popup menu is the "File Flags" menu.  The next icon is the
"Mode" popup menu, which shows the window's current mode and allows it to
be changed.

Finally, if you turn horizontal scrollbars off (via the 'horScrollBar' flag
in the "Config:Global:Preferences:Window" dialog, you haven't lost any real
estate. Furthermore, when tiling windows vertically, you actually have
*more* real estate.


          Modes

Each window in Alpha is always in a single "mode", such as the "C++" mode,
or the "TeX" mode.  A mode describes bindings and variable values
particular to that mode.  The mode of the frontmost window is displayed and
can be changed via the status bar.

Alpha sets modes for new windows based on file name suffixes.  For
instance, "files.c" is started up in mode "C++" because of the ".c" suffix.
Below are some examples of standard suffixes recognized by Alpha.  These
suffixes can be changed via the 'Suffix Mappings…' item in the "Config" menu.
The default mode is "Text".

    .r                                C
    .cc, .cp, .cpp, .CPP, .C        C++
    .f .fcm .for .FOR                Fort
    .tcl                            Tcl
    .tex, .sty, .ltx, .dtx, .ins    TeX
    .pl                                Perl
    .html .htm                        HTML

Bindings for a specific mode can be specified by passing the desired mode as
the last argument to a 'Bind' command (see "Key Bindings").

Alpha has two different types of immediately visible flags and variables:
global and per-mode flags. These can be changed in separate submenus under the
Config menu.

"Mode" flags and variables are instantiated separately for each mode.
These are inspected and set via the "Config:Current Mode" menu.  Changing
these values affects every window in that mode, but doesn't affect windows
in other modes.

The variables displayed in "Config:Current Mode" are all the variables that
the current mode cares about. The "Config:Current Mode:Menus And Features…"
item allows you to specify which of the extra menus should be present
whenever the frontmost window is in that mode.

See here for more information on defining your own modes.

See here for information on removing existing modes (for disk space).

        Features

Alpha has a very flexible mechanism for adding extensions. There are many
extensions included in the basic Alpha distribution. Others can be
downloaded from one of Alpha's internet sites (there are now more than
thirty such packages available). The 'Config:Package Prefs' menu allows you to
update modes, menus, and extensions quickly and easily by downloading small
update files from the internet.

You can customize Alpha by activating and deactivating these extra
features. They come in two flavors, "menus" and "features". A "menu" is a
stand-alone menu which is attached to the menu bar, while a "feature" is
some functionality which doesn't have a menu connected to it. However, some
features add a submenu or menu items to a submenu. Thus, there is only a
technical difference between "menus" and "features". They both give you
some additional functionality.

You activate the extra menus and features by using the menu item
"Config:Preferences:Menus And Features…"

See here for more information on how to write your own menus and features.

Click here for a list of all installed menus, features, and modes.



          File Comparison

Alpha can create UNIX "diffs" of two text files. Among other things, diffs
allow you to easily pinpoint what has changed between two different
versions of the same file.

Alpha's interface (under the "Utils" menu) allows you to compare either the
two topmost windows, or two arbitrary files or entire folders). Alpha opens
the two files in windows at the top of the screen with the diff file at the
bottom. You can navigate between individual differences in the diff file by
using the Up and Down arrows. Pressing either a carriage return or the
Enter key displays the affected portions of the two files in the above
windows.

I'm currently using a hack of QUED's GNU diff port.  My hack allows
it to work as an AppleEvent server.  However, it handles most errors by
quitting without responding, and handles only a single message before
quitting. It also doesn't deal with folders.

The interface is a 'dosc' script event containing the command-line
arguments that would be used in running 'diff' from a UNIX shell (see
here).  The result is the diff.  On the command line, file names containing
spaces can be specified by delimiting the entire file name with double
quotes.  The source for my version of the diff application (crude though it
is), is available in pub/faculty/keleher/Alpha on cs.umd.edu.

Bugs: The files must have line Mac terminations.



          HyperText

Alpha's hypertext is both more and less powerful than systems that use
markup languages such as HTML. It's more powerful because the action
taken upon hitting a hypertext link is any arbitrary Tcl script rather
than just navigation. It's less powerful because the generality doesn't
allow a standard notion of going "back" or "forward". In any case, two
points:
    1) The hypertext is only intended for Alpha documentation, and links
    should not need to be created by anyone who isn't writing docs.

    2) 'pushMark' is called before any hypertext link is executed. This
       allows you to return to the previous spot by "Pop Mark"ing (from the
       Edit menu).

If you *must* create hypertext links, use the insertColorEscape command.



          Limitations

- Apple's listproc seems to have a total size limit of 32k characters.
  This effectively limits tag searches to about 4000 function names.


          Preferences

Alpha saves settings between sessions by writing them to files in an
"Alpha" sub-folder of the system preferences folder.  Additionally, Alpha
will source a file called "prefs.tcl" from this sub-folder if it exists.
You can view or remove the settings currently being saved there at any time
via the "View/Remove Saved Settings…" from the Edit menu. You can edit
the prefs.tcl file via the "Config:Global:Edit Prefs File" item.

Never add manually add text to the defs.tcl or arrdefs.tcl files in the
preferences folder. These files are automatically generated and read by
the addDef etc. functions. If you need to save variable definition from
Tcl code, addDef etc. is your friend.

If you want to have arbitrary code executed on startup, you can manually
place this in the prefs.tcl file.

Holding down the shift key at startup causes Alpha to skip all preferences
files.


          Changing Alpha's Behavior

Alpha's behavior can be modified in five primary ways. The first is by
changing flag and variable values. Mode-independent flags and variables are
under the "Config:Preferences" menu. Mode-dependent flags and
variables are in "Config:Mode Prefs:Preferences". Values of all of these
flags and variables are saved when Alpha exits.

The second method is to write an 'extension'. See the 'Extending Alpha'
help file for details. Extensions are conveniently packaged pieces of Tcl
code which have a startup section and a main section and are labelled via a
name and version number. They may be conveniently turned on or off using
the Packages menu, and can be distributed to other Alpha users without the
requirements for complex installation instructions.

The third method is to add bindings or Tcl procs to 'prefs.tcl', Alpha's
preference file.  This file is accessible from the "Config" menu as well.
'prefs.tcl' is sourced at the end of Alpha's startup procedure.

The fourth way to modify Alpha's behavior is to create mode-specific prefs
files. These files are created through the Config menu. Mode-specific prefs
are loaded after the corresponding mode has been entered for the first
time.

The final recommended way to modify Alpha is to create files that are
sourced after corresponding files in Alpha's :Tcl:SystemCode folder. See
here for more details.

Finally, you could just hack the files in SystemCode directly. However,
you should definitely know what you are doing if you resort to this method,
and it's definitely *not* portable from one version of Alpha to the next.



          Internet Config

"Internet Config" is a freeware utility that holds system-wide preferences,
especially preferences that might be accessed by more than one
application.  For example, Internet Config stores pointers to helpers for
web services, ftp, etc.

Alpha supports "Internet Config" in the following ways: (i)
command-clicking on highlighted text causes the text to be sent to Internet
Config to be launched, (ii) the Internet Config menu allows either Internet
Config itself, or several of it's internet helpers, to be started, and iii)
Alpha can query Internet Config for path names in the "Config:Helper Apps…"
dialog.

Click here for more information.  Once you have installed it and set up
your ftp helper app through Internet Config, you can retrieve the entire
package by clicking here.

The "URLs" submenu allows you to store a few commonly used URLs and to
launch them, regardless of what helper they are directed to.

For instance, my menu includes

New York Times       "http://www.nytimes.com/info/contents/contents.html"
Latest TCL Source    "ftp://ftp.aud.alcatel.com/tcl/ftp.smli.com/mac/"
Down                 "ftp://keleher:[e-mail]/down/"

where 'passwd' is replaced by my real password (and is understood by
Anarchy, among others).

The function icURL can be to send URLs to internet config. For instance, I
have the following proc defined in my prefs that allows me to access any
arbitrary directory of my unix box at school merely by typing "ftp <dir>":

    proc ftp {{arg ""}} {
        icURL "ftp://keleher:[e-mail]/$arg"
    }

The 'Finger' item sends a fetchurl event to Peter Lewis's "Finger" program.


          Calculator

Alpha now has its own calculator :-), entirely implemented in Tcl.  This is
just a quick-and-dirty RPN stack calculator, works on both signed and
unsigned decimals, hex integers, and floating point.  I put it together for
my own use, not yours, but feel free to use it as long as you don't complain
about what it doesn't do. Improvements, of course, are welcome.

Operations:
    +,-,*,/,|,&,%    Top    of stack is    'y', next is 'x'. Does x OP    y.
    ~                bitwise NOT
    ^                x eor y
    <                x << y
    >                x >> y
    c                change y's sign
    q                dup    y
    i                swap x and y
    m                switch signed/unsigned/hex modes
    x                show current mode
    h or ?            help
    <delete>        pop    stack
    <space>            enter number

Invoke from the File menu, holding down the shift key.



          Templates

Temporary marks can also be used to construct templates.
The file "templates.tcl" contains basic template support, and the
Vince's Additions package (an extension you may download) provides a
more feature rich version.  Templates are pieces of code/text with
predefined 'template-stops' at which the user will want to enter
information.  For instance, in C mode, you can save a lot of typing by
using 'for' templates, which insert 'for (•;•;•) { • }'.  By default
'tab' and 'shift-tab' are used to move forwards and backwards between
the bullets (which are the template-stops).

As of Alpha 7.0, the old 'electricAlias' package no longer functions
correctly.  It would be relatively easy for a user to fix it up to
work again.  However, similar functionality is provided via Alpha's new
built-in templates and extended by Vince's Additions, so you'll
probably be happy just to use them.

NOTE: TO USE TEMPLATES YOU MUST SET YOUR ELECTRIC TAB PREFERENCE!
Otherwise the tab key will just insert a tab (surprise, surprise).
There is a global setting, and some modes have their own setting
which will over-ride the global one.

If your code needs to insert templates, you should use the following
procedures:

    elec::Insertion {args}
    elec::CenterInsertion {args}
    elec::ReplaceText {start end args}
    elec::Wrap {left right}

These all do the 'obvious' thing.  The only non-obvious point is
that the template-text you give these procedures should mark its
template stops (bullets '•') with DOUBLE BULLETS '••'.  So a 'for'
template is "for (••;••;••) \{ •• \}".  Why, you may ask?  This
is because more advanced template mechanisms can put more information
between the bullets.  The simplest such instance you may wish to
support is to put a descriptive name for the template stop inbetween:
"for (•start•;•test•;•increment•) \{ •loop body• \}"

          Ftp Browser

The 'FTP' menu allows quick access to files on a remote ftp server, useful
for those that work on both unix and mac systems. You should have Anarchie
or Fetch installed as your ftp client. Popup menu in title of any "remote"
window allows repeated access to those directories.

More docs later, once someone sends them to me. Please volunteer....




          Deconstructing Alpha

Use the 'Config:Package Prefs:Uninstall A Package…' menu item to remove modes
menus or extensions you don't use to save disk space. This *permanently*
removes tcl and help files pertaining to the offending modes and menus.
Only a re-installation can get them back.



Remember, Alpha's official home site is:

        http://www.bcity.com/alphatext